Summary

Why

Cloud Agent sessions need a stable, authenticated SDK surface so external clients can attach without depending on sandbox topology or exposing internal wrapper details. The facade gives @kilocode/sdk/v2 consumers a narrow public contract for owned root sessions while preserving durable admission, runtime fencing, and cold-history access when a wrapper is unavailable.

What was done

• Add an authenticated /kilo facade backed by a per-user UserKiloFacade Durable Object. It supports owned root-session listing, detail and message reads, async text prompts with optional Kilo agent/model selection, abort, global SSE, and session-scoped SSE.
• Keep reads live-first through the sandbox wrapper /kilo-proxy path, with a persisted session-ingest fallback for session detail and transcript reads. Cold transcript pages use native cursors, bounded materialization, and omission metadata for oversized or forward-compatible unsupported items.
• Route prompt_async and abort through CloudAgentSession instead of directly to the wrapper so admission and interruption remain durable across cold runtimes.
• Add a fenced wrapper global-feed producer path: the wrapper converts runtime SSE into an authenticated WebSocket feed, and the facade filters, virtualizes, and fans events back out as public SSE.
• Keep the public projection intentionally narrow: child sessions remain hidden, unsupported SDK routes return 501, typed outer routing fields are virtualized, and nested owner-visible payload content is preserved.

High-level SDK facade architecture

sequenceDiagram
  autonumber
  participant SDK as @kilocode/sdk/v2 client
  participant Worker as cloud-agent-next Worker
  participant Facade as UserKiloFacade DO
  participant SessionDO as CloudAgentSession DO
  participant Wrapper as sandbox wrapper
  participant Runtime as in-process Kilo SDK server
  participant Ingest as session-ingest / SessionIngestDO

  SDK->>Worker: Authenticated /kilo/* request
  Worker->>Facade: Route with authenticated user context

  rect rgb(235, 245, 255)
    Note over SDK,Ingest: Live-first session detail and transcript reads
    Facade->>Wrapper: GET /kilo-proxy/session/:id[/message]
    Wrapper->>Runtime: Forward SDK read
    alt Runtime is available
      Runtime-->>Wrapper: SDK-compatible response
      Wrapper-->>Facade: Return live response
    else Runtime is unavailable
      Facade->>Ingest: Read persisted snapshot or transcript page
      Ingest-->>Facade: Bounded cold projection with native cursor metadata
    end
    Facade-->>SDK: Projected public response via Worker
  end

  rect rgb(245, 245, 235)
    Note over SDK,Wrapper: Durable mutations
    SDK->>Facade: POST prompt_async or abort via Worker
    Facade->>SessionDO: Admit prompt or interrupt execution
    opt Runtime is ready
      SessionDO->>Wrapper: Dispatch admitted work
    end
    Facade-->>SDK: Accepted or idempotent response via Worker
  end

  rect rgb(240, 250, 240)
    Note over SDK,Runtime: Fenced public event stream
    Runtime-->>Wrapper: /global/event SSE
    Wrapper->>Worker: Authenticated producer WebSocket upgrade
    Worker->>SessionDO: Validate producer identity
    SessionDO-->>Worker: Producer accepted
    Worker->>Facade: Forward producer socket
    Wrapper-->>Worker: Runtime event frames
    Worker-->>Facade: Forward event frames
    Facade-->>SDK: Filtered and virtualized public SSE
  end

Architecture decision

Decision: expose Cloud Agent sessions through a narrow authenticated /kilo facade that implements the relevant @kilocode/sdk/v2 contract, rather than introducing a Cloud Agent-specific client API.

Context: existing UI clients already integrate with the Kilo SDK for session reads, conversation flows, async prompts, aborts, and event consumption. Cloud Agents provide similar capabilities, but their internal lifecycle differs: sessions can move between live sandbox runtimes and persisted history, mutations need durable admission, and wrapper topology must remain private.

Rationale: implementing the relevant Kilo SDK surface gives those clients a familiar integration path with minimal additional client-side work. The facade adapts the Cloud Agent lifecycle behind that contract: reads are live-first with bounded persisted fallback, prompts and aborts continue through CloudAgentSession, and public events are filtered and virtualized before reaching SDK consumers. The initial facade intentionally supports only the subset needed by external clients; unsupported SDK routes return 501 rather than implying broader compatibility.

Alternatives considered:

• Create a Cloud Agent-specific client API. This could mirror the internal Cloud Agent lifecycle more directly, but UI clients would need a second integration for substantially the same conversation flows. It would also create another protocol to document, maintain, and evolve alongside the Kilo SDK.
• Expose sandbox wrappers or runtime SDK servers directly. This would reduce facade code, but it would couple clients to sandbox topology and runtime availability. It would also bypass the stable ownership boundary, durable mutation path, persisted-history fallback, and public event filtering provided by the facade.

Consequences: Cloud Agents gain an adaptation layer that must preserve SDK-compatible behavior across live and cold sessions. In return, existing Kilo SDK clients can integrate with Cloud Agent-backed sessions without adopting a parallel protocol, while the internal runtime remains private and independently evolvable.

Verification

• Exercised the authenticated facade locally through @kilocode/sdk/v2, including session attach and reads, async chat, abort, and event consumption.
• Built a quick VS Code extension proof of concept against the facade and verified that an extension can attach to a Cloud Agent-backed SDK session and use the conversation flow.

Visual Changes

N/A

Reviewer Notes

• Public SDK access is limited to user-owned Cloud Agent-backed root sessions with current organization access. Child sessions remain hidden.
• Cold transcript pages use an 8 MiB aggregate budget, a page size up to 100, and at most 128 persisted message-row scans. Oversized rows are skipped internally; if a native cursor cannot safely represent progress, the facade returns 413 rather than an ambiguous continuation.
• Global-feed producer fencing is connection-oriented: identity is validated at WebSocket upgrade and facade acceptance time, and newer wrapper connections replace older sockets. Frames are not revalidated against CloudAgentSession after socket acceptance.
• Deploy session-ingest before cloud-agent-next; the facade consumes additive session-ingest RPCs. The cloud-agent-next deployment must include the Wrangler v5 migration for the SQLite-backed UserKiloFacade Durable Object.
• Existing warm wrappers do not expose the new /kilo-proxy or global-feed producer paths. Recycle or drain wrappers during rollout so live SDK reads and SSE delivery consistently use the new wrapper behavior.